LogoENEnglish

مدیریت خطاها، forbidden.js و instrumentation.js در Next.js — بازیابی با ظرافت و نظارت هوشمند

Next.js ابزارهایی قدرتمند برای مدیریت خطاها، کنترل دسترسی، و مشاهده‌پذیری ارائه می‌دهد. این مقاله نحوهٔ استفاده از error.js برای نمایش fallback UI، استفاده از forbidden.js برای نمایش صفحه 403، و استفاده از instrumentation.js برای ردیابی خطاها و عملکرد سرور را آموزش می‌دهد.

error.jsforbidden.jsinstrumentation.jsError Boundary

~3 دقیقه مطالعه • بروزرسانی ۷ آبان ۱۴۰۴

۱. error.js — مدیریت خطاهای زمان اجرا


فایل error.js به‌عنوان Error Boundary عمل می‌کند و هنگام بروز خطا در یک segment، UI جایگزین نمایش می‌دهد.

'use client'

export default function Error({ error, reset }) {
  useEffect(() => {
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

ویژگی‌ها:

  • error.message: پیام خطا برای دیباگ
  • error.digest: شناسه هش برای تطبیق با لاگ‌های سرور
  • reset(): تلاش برای رندر مجدد segment

۲. global-error.jsx — مدیریت خطای سراسری


برای مدیریت خطا در سطح root layout، از فایل global-error.tsx استفاده کنید. این فایل باید شامل تگ‌های html و body باشد.

'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

۳. GracefullyDegradingErrorBoundary — بازیابی ظریف


این کامپوننت HTML فعلی را قبل از خطا ذخیره کرده و در صورت بروز خطا، آن را بدون hydration نمایش می‌دهد.

if (this.state.hasError) {
  return (
    <>
      <div dangerouslySetInnerHTML={{ __html: cachedHTML }} />
      <div className="notification">An error occurred</div>
    </>
  )
}

۴. forbidden.js — نمایش صفحه 403


فایل forbidden.js برای نمایش UI هنگام فراخوانی تابع forbidden() در فرآیند احراز هویت استفاده می‌شود.

export default function Forbidden() {
  return (
    <div>
      <h2>Forbidden</h2>
      <p>You are not authorized to access this resource.</p>
      <Link href="/">Return Home</Link>
    </div>
  )
}

۵. instrumentation.js — مشاهده‌پذیری و ردیابی خطاها


فایل instrumentation.ts برای ثبت عملکرد سرور و گزارش خطاها استفاده می‌شود.

export function register() {
  registerOTel('next-app')
}

export const onRequestError = async (err, request, context) => {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({ message: err.message, request, context }),
    headers: { 'Content-Type': 'application/json' },
  })
}

پارامترها:

  • error.digest: شناسه خطا
  • request: اطلاعات مسیر، متد، و headerها
  • context: نوع router، نوع route، منبع render، و دلیل revalidation

۶. تعیین runtime


برای اجرای متفاوت در Node.js یا Edge:

if (process.env.NEXT_RUNTIME === 'edge') {
  return require('./register.edge')
} else {
  return require('./register.node')
}

جمع‌بندی


Next.js با ابزارهایی مانند error.js، forbidden.js و instrumentation.js امکان مدیریت خطا، کنترل دسترسی، و نظارت دقیق را فراهم می‌کند. این ابزارها تجربه کاربری را بهبود می‌بخشند و توسعه‌دهندگان را در ساخت اپلیکیشن‌های مقاوم و قابل اعتماد یاری می‌دهند.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article